Skip to contentSkip to conversation

Documenting hardware support (was: Repository Growth)

DISCUSSION [email protected] 1 participant 1 message Sep 19, 2018

lore
Share & tools
lore
#0 lore raw

I apologize in advance if this is not formatted as plain text and for "top posting"... I'll try to improve my email etiquette.

Idea: Explain OpenBMC hardware environments
I would like to see a brief explanation of OpenBMC's relationship to its BMC and host server. In my (limited) understanding, the relationship between the two hardware platforms (how the BMC services its host) is the essence of what OpenBMC adds to the openembedded project, so it deserves an explanation in the docs repo.

Specifically, this is required background to discuss OpenBMC support for various BMCs and host machines. - I understand BMC hardware support is in the form of Board Support Packages (BSP) which come from the openembedded project.
- I understand host machines are supported from meta-layers.

I propose to enhance the openbmc/docs docs to include talk about how to find board support layers (e.g., meta-aspeed), and machine layers (e.g., meta-intel). For each supported BMC and each supported host, I want to understand:
- where to find more information about the device (e.g., its proper
name, manufacturer or specs)
- how OpenBMC supports that hardware. Example: OpenPower systems use
the meta-openpower layer and various openpower-* layers such as openpower-power-control.

I have a limited hardware background, but I presume such a document would be a good place to introduce any hardware-facing features that BMCs typically provide (i.e., added to the openembedded layer). For example:
- firmware update
- event log processing
- host console or video

Also, I believe such a document would be a good place to anchor the guide for how to add a new BMC or host machine.

	-----------------------------------------From: "Andrew Geissler" 

To: [email protected]
Cc: "OpenBMC Maillist", "Patrick Venture"
Sent: Wednesday September 19 2018 1:09:52PM
Subject: Re: Repository Growth

Quoted 11 lines · On Wed, Sep 19, 2018 at 12:56 PM wrote:

Date: Wed, 19 Sep 2018 09:42:16 -0700
From: Patrick Venture
To: [email protected]
Cc: OpenBMC Maillist , Brad Bishop
, Nancy Yuen , [email protected]
Subject: Re: Repository Growth
Message-ID:

Quoted 6 lines

Content-Type: text/plain; charset="UTF-8"

Quoted 3 lines · Adriana Kobylak
Quoted 1 line · Patrick Venture

With the growth of number of repositories, it might be

overwhelming to

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines

someone who wants to set things up.

I'd like to write up a directory that groups the repositories

by

Quoted 1 line
Quoted 1 line
Quoted 1 line

purpose. I wasn't sure if this made sense, so I wanted early

feedback

Quoted 1 line
Quoted 1 line
Quoted 1 line

before I started. The maintenance of it would be horrible for

one

Quoted 1 line
Quoted 1 line
Quoted 1 line

person, but if someone wants their repository to have details

and so

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines

on they can add it.

I think it's important or useful to know what's out there and

how

Quoted 8 lines
Quoted 5 lines
Quoted 3 lines

things work together or don't, and what options there are for developers.

+1 . Do you have a template in mind on how this could look like?

I've been toying around with some ideas on how to organize the information. Grouping the subtrees together is a no-brainer, but

many

Quoted 5 lines

daemons don't really fit into a category. Maybe that's fine, maybe then it'd be uncategorized.

I was imagining:

Quoted 8 lines

{repository name}
{short description}
works with: {list of related pieces}

for instance:
"""
### phosphor-hwmon
phosphor-hwmon periodically reads and reports hwmon sensor values

to dbus.

Quoted 4 lines

works with: phosphor-host-ipmid
"""

You don't need to run phosphor-host-ipmid to use phosphor-hwmon,

and

Quoted 5 lines

phosphor-pid-control and other daemons can also listen to sensor values or read them over dbus, so I don't know how complete such a list would need to be. So maybe the list should be less explicit. I realize that the recipes themselves reveal the true dependencies, either virtual or specific and I don't want to repost information.

I

Quoted 1 line

just want to present a better interface to the set of repositories

and

Quoted 6 lines

how they work together (or don't) than github has.

Quoted 2 lines
Quoted 2 lines

Thoughts?

I had the same idea from reading through the presentations recently

linked to on this mailing list.

Quoted 2 lines

OpenBMC lists its features on its front page

(https://github.com/openbmc/openbmc [1] README) and suggests there is more information in https://github.com/openbmc/docs. [2] However, the information is not structured as well as it could be for someone to learn about each feature. I propose to list each feature along with the following information (as applicable):

Quoted 8 lines

- reference an external website or standard
- categorize: host-facing, management network facing, application
- explain terminology (give synonyms)
- explain 1 or 2 use cases
- link to the docs (which should explain customizations)
- link to the source code repo

I would start with the features listed in openbmc/README, and add

features (or interfaces?) from James's presentation:

Quoted 3 lines

- Host interfaces: KCS, BT, mbox, IPMB, USB, VGA
- Network Interfaces: Redfish, https, ssh, rmcp+
- Applications: EWS, KVM, IPMI, FSC, SEL, SOL, Chassis Control,

ASD, Firmware Update, Configuration Manager, Sensor Monitor

Makes sense to me.

Per the mailing list discussion yesterday on the hackathon, I'm also starting to work on some "digging into openbmc coding" type docs. That will probably deserve it's own directory?
- Getting Started: Dev env setup, hello world via SDK/QEMU, adding a new system/layer, customizing webui and other items for new system, bitbake using local repos, ...

Quoted 7 lines

So, the proposal is to group repos by feature and interface.

Quoted 3 lines
Quoted 2 lines

Patrick

Links:
------
[1] https://github.com/openbmc/openbmc
[2] https://github.com/openbmc/docs.